Publish versioning, roadmap, and dependency policies for v2 - #3215

The inconsistency. This PR adds two policy documents that both make a normative statement about when a dependency floor raise may ship in a minor release, and they don't agree on scope. docs/versioning.md (line 46, under "These do not [count as breaking], and can ship in a minor release") says unconditionally: "raising a dependency's minimum version when the SDK needs newer functionality … called out in the release notes (the dependency policy covers the first)". DEPENDENCY_POLICY.md line 18 instead says: "Raising a floor within the same major version of a dependency is a minor-release change and is called out in the release notes; see the versioning policy."

Why the qualifier matters. In a document whose stated purpose (per the PR description) is to publish commitments rather than descriptions — read by the SEP-1730 tier assessment — a scoped qualifier reads as deliberate. "Within the same major version" plainly implies that raising a floor across a dependency's major version is a different, larger kind of change. That reading is reinforced by the same file already treating dependency majors specially ("no upper bounds unless a dependency's next major version is known to break the SDK"). versioning.md, by contrast, admits any needed-functionality floor raise into a minor with no such carve-out.

Why a reader can't resolve it. The deferral is circular: versioning.md says "the dependency policy covers the first", and DEPENDENCY_POLICY.md says "see the versioning policy". Neither page claims precedence, so neither text settles which rule governs the cross-major case.

Concrete walk-through. Suppose the SDK decides it needs a feature that first ships in pydantic 3.0, so the floor moves from pydantic>=2.12.0 to pydantic>=3. (1) A maintainer following versioning.md's non-breaking list ships this in mcp 2.(X+1).0 — the text permits any minimum-version raise motivated by needed functionality. (2) A downstream user who read DEPENDENCY_POLICY.md's "within the same major version" qualifier concluded such a raise would wait for mcp 3.0 and kept pydantic<3 pinned in their environment. (3) An unpinned mcp upgrade to the new minor makes their environment unresolvable, and each party can point at one of the two pages to justify their expectation. The whole point of these pages is to prevent exactly that dispute.

Strictly speaking the two statements are logically compatible — asserting the same-major case is minor doesn't assert the cross-major case is major; it's implicature, not contradiction. But either the qualifier is intentional (and versioning.md's unconditional wording is then wrong) or it isn't (and the qualifier is misleading scope-narrowing). One of the two sentences needs an edit either way.

Fix. Pick one: (a) if cross-major floor raises are meant to be minor-eligible, drop "within the same major version" from DEPENDENCY_POLICY.md line 18; or (b) if they're meant to wait for the next mcp major, add that case explicitly to versioning.md's breaking-change list (e.g. "raising a dependency floor across that dependency's major version"). Docs-only, one-sentence change in files this PR introduces — nothing breaks on merge, hence not blocking.

What the inconsistency is. The new Issue Triage section (CONTRIBUTING.md:59) publishes a closed label taxonomy as a normative contract: "The labels follow the shared MCP SDK taxonomy: one type (bug, enhancement, question), one status (needs confirmation, needs repro, ready for work, good first issue, help wanted), and — once actionable — one priority". Two independent sources in the same repo contradict that enumeration: the same document's own pre-existing text, and the issue-template automation that actually applies labels to every new issue.

Contradiction 1 — within CONTRIBUTING.md itself. Line 51 (pre-existing) says "Issues labeled needs confirmation or needs maintainer action are not ready for work" — treating needs maintainer action as an in-use status label, grouped with needs confirmation (which is in the enumeration). But the closed status set published eight lines later omits it, and needs maintainer action appears nowhere else in the repo. A reader cannot map the label the document itself uses onto the taxonomy the document declares every issue follows.

Contradiction 2 — the issue-template automation. Verified in the checkout:

• .github/ISSUE_TEMPLATE/feature-request.yaml line 3: labels: ["feature request"] — a label absent from the taxonomy, whose type label for this class is enhancement. No template applies enhancement, so it is absent from every template-created feature issue.
• .github/ISSUE_TEMPLATE/bug.yaml line 3: labels: ["need confirmation"] — no 's', mismatching both the pre-existing line 51 and the new taxonomy at line 59 (both spell it needs confirmation). One of the two spellings is not a real label. The template also applies no bug type label at all, so a template-filed bug starts with only a (misspelled) status label.
• question.yaml (labels: ["question"]) is the only template consistent with the taxonomy — confirming the mismatches are specific and real, not a misreading.

Step-by-step proof. (1) A user files a bug via the template; GitHub applies need confirmation and nothing else. (2) A triager or the SEP-1730 tier check follows the just-published contract and queries label:"needs confirmation" or expects one type label per issue — the query misses the issue, and the one-type invariant is already violated at creation. (3) Similarly, a contributor reading the taxonomy queries label:enhancement for feature work and finds nothing, because every template-filed feature request carries feature request instead. The contract published by this PR is falsified by the repo's own automation on every template-filed issue.

Why this belongs in this PR. The templates and line 51 pre-date the PR, but the PR is what introduces the closed enumeration and canonizes it as the taxonomy the SEP-1730 tier assessment measures — the contradiction only becomes a contradiction once this text merges. This is a policy-docs PR whose substance is textual precision, so reconciling is squarely in scope.

How to fix. Either (a) align reality with the taxonomy — add bug + needs confirmation to bug.yaml's labels:, change feature-request.yaml to enhancement, and either add needs maintainer action to the status enumeration or rewrite line 51 to use a listed label — or (b) keep the labels as they are and add a sentence mapping them onto the taxonomy. Option (a) is a few one-line edits and makes the published contract true.

Impact/severity. Nothing breaks at merge — this is a docs/process inconsistency, so nit severity. All six verifier confirmations (three per source bug) agreed on the facts and on nit; there were no refutations.

What the page promises vs. what the SDK does. The new Deprecations section states categorically that SDK API deprecations are "marked with [typing_extensions.deprecated], so static type checkers flag every call site and Python emits a DeprecationWarning at runtime," and the closing bullet reinforces it: "one release of warning at minimum before an SDK API is removed." The SDK already has a formally documented SDK-API deprecation that goes through neither channel.

The counterexample. src/mcp-types/mcp_types/version.py:48-51 declares SUPPORTED_PROTOCOL_VERSIONS with the docstring "Deprecated: prefer HANDSHAKE_PROTOCOL_VERSIONS or MODERN_PROTOCOL_VERSIONS. Kept as the union for v1.x compatibility." It is listed in that module's __all__ (line 16) and reachable via the documented mcp.types.version path, so it is public surface under this page's own definition ("every name exported ... by mcp_types" plus documented import paths). docs/migration.md:552 gives it a dedicated section heading — "SUPPORTED_PROTOCOL_VERSIONS deprecated; LATEST_PROTOCOL_VERSION changed meaning" — so this is an official, documented deprecation, not an informal aside. It is not a protocol deprecation either: it does not appear in docs/deprecated.md and carries no MCPDeprecationWarning.

No warning mechanism exists. Grepping src/ shows every @deprecated usage is on a function or method (mostly the MCPDeprecationWarning protocol set); nothing marks this constant, and there is no module __getattr__ in mcp_types/version.py or the mcp/types alias. So type checkers do not flag call sites and Python emits no warning of any kind at runtime — the opposite of what this page promises.

Step-by-step proof. (1) A user reads this policy page and audits per its implied procedure: run the suite with warnings-as-errors and type-check with pyright, expecting every deprecated SDK API to surface. (2) Their code does from mcp.types.version import SUPPORTED_PROTOCOL_VERSIONS. (3) Pyright reports nothing (no @deprecated marker) and the test run emits no warning (plain module attribute access). (4) They conclude they use no deprecated SDK APIs. (5) At 3.0, the constant is removed — per the migration guide it is deprecated and "kept for v1.x compatibility" — and the user gets zero of the promised "one release of warning at minimum."

Why the named mechanism cannot cover this class. typing_extensions.deprecated is a decorator for callables and classes; it structurally cannot be applied to a module-level constant. So the categorical wording overlooks a class of deprecation the SDK already has, and the only runtime option for constants is a module __getattr__ shim — which the SDK does not use.

Fix (either side works). Docs-side: qualify the sentence, e.g. "functions, methods, and classes are marked with typing_extensions.deprecated; deprecations that cannot carry the marker, such as module constants, are announced in the migration guide." Code-side: add a module __getattr__ in mcp_types/version.py (and the mcp.types.version alias) that emits DeprecationWarning on SUPPORTED_PROTOCOL_VERSIONS access, which would make the page's claim true as written.

Severity. Docs-only imprecision in a policy page whose substance is the accuracy of these commitments — worth fixing in this PR since it introduces the claim, but nothing breaks at merge, so it is not blocking. All four verifiers confirmed independently; none refuted.

The inaccuracy. DEPENDENCY_POLICY.md line 26 states that vulnerabilities in the SDK's own code "follow the reporting process and response commitments in SECURITY.md". SECURITY.md (unchanged by this PR) contains exactly three things: a supported-versions table, a "Reporting Security Issues" section (use GitHub Security Advisories; do not use public issues/discussions/PRs), and a "What to Include" checklist. There is no response commitment of any kind — no acknowledgement window, no triage SLA, no fix or disclosure timeline. The phrase "To help us triage and respond quickly" is a request to the reporter, not a commitment by maintainers.\n\nWhy the pointer dead-ends. The only response-time commitment this PR publishes anywhere is CONTRIBUTING.md's new triage table, where P0 (which includes High/Critical-severity security issues) is "resolved within 7 days". But that table explicitly governs the public issue tracker — and the very same section (plus SECURITY.md itself) says security reports must not go through the issue tracker. So a security reporter following the chain has no committed response at all: the private channel makes no commitments, and the channel with commitments is the one they're told not to use.\n\nThe accurate wording exists in this same PR. docs/versioning.md phrases the identical cross-reference correctly: "The security-specific version of this table, and how to report a vulnerability, is in SECURITY.md" — describing what the file actually contains, without asserting commitments that don't exist. That contrast shows this is a wording slip in DEPENDENCY_POLICY.md, not a deliberate claim.\n\nWhy it matters for this PR specifically. Per the PR description, these pages are written as "commitments rather than descriptions" for the SEP-1730 tier assessment. A tier assessor or vulnerability reporter who follows the pointer to learn what response to expect finds nothing, and can reasonably conclude the policy chain is broken — the one failure mode a policy-publication PR is trying to avoid.\n\nStep-by-step proof. (1) A researcher finds a vulnerability in the SDK's own code and reads DEPENDENCY_POLICY.md's "Security in the SDK itself" section, which promises "response commitments in SECURITY.md". (2) They open SECURITY.md and read it in full: supported-versions table → GitHub Security Advisory channel → what-to-include checklist. No commitment appears. (3) They check whether commitments live elsewhere and find CONTRIBUTING.md's P0 row ("resolved within 7 days") — but its scope is issue-tracker labels, and both CONTRIBUTING.md and SECURITY.md direct security reports away from the issue tracker. (4) The promised commitments do not exist anywhere the reporter is allowed to go. One charitable reading — that the supported-versions table ("which lines receive security fixes") is itself a "response commitment" — doesn't hold: that is a support-scope statement, not what a reporter would understand as a response commitment (what happens, and when, after filing).\n\nFix. Either (a) soften the sentence to "…follow the reporting process in SECURITY.md", a two-word deletion that makes it accurate, or (b) if response commitments are meant to exist for the tier assessment, add them to SECURITY.md (acknowledgement window, triage SLA, fix/disclosure timeline) so the pointer becomes true. Docs-only; nothing breaks at merge, hence not blocking.